RSCcompiler 2.1

Copyright © 1999 Guillaume Sabouraud

Read this document carefully. It's not long and necessary to avoid any runtime problem. Users of previous versions of this program should read the historic section to know quickly about the latest changes.

This utility is freeware but I ask you to add something in the credits section of your help file or about screen if you use it for any freeware or shareware that you distribute and for which you have used RSCcompiler.

Historic

I initially created this program to add the support for new languages on my program ChemTools and here it is for all other users as it might be useful not only for me.

Many thanks to Jens Kaminski, the author of HexEditor (which was necessary to accomplish this work) and of RSC Creator, a program that does the same work that RSCcompiler (but taking a text file as an argument and not creating the constant definitions) and which inspired me a lot.

V 1.0 : October 25th 1998. First public release

V 1.01 : Ocober 27th 1998. Fixed a tiny bug that made an illegal rsc file because of an allocation error for some files. Removed a stupid and unnecessary alert dialog. Removed a restriction to the file selection dialog which allowed to open only the files generated by the data application and not the standard opl data files genrated by opl functinos. I start to work on the reverse program (RSCdecompiler) and on an RSC editor (RSCeditor).

V 1.1 : October 29th 1998. The generated constant file had different constants according to the language (stupid, no?). Well, I've fixed this and as soon as I understand how the NAME statement is stored in the resource file, it will be possible to generate named files so that you can use more than one resource in a program (current name is AAAA according to an example heading found in Symbian documentation). You can now choose the destination files (they will be saved in an ini file) and to build or not the constant file. If you don't need the constant file, just choose the value 0 for the constant field. There is also a special feature to handle the special characters you can't type in the data application such as the CHR$(10) line break often used to display a two line text on a button ; the syntax is "\$n\" where n is the ASCII code you want to put.

V 2.0 : November 23rd 1998. After one month of intensive use, I am now able to release this new version with major changes. The compiler is much quicker now (up to four times and probably more in some cases !) as it now works in a dynamically allocated space in the RAM instead of writing to a file as one goes along. The source database is automatically compacted if needed. More options are available now : you can input an integer to replace the name statement ; you can define the letter codes for the language fields of your data file and add them to the resource you generate. See below for how to use these new functions. Warning : the ini file from the older version has not the same format so you'll have to set your preferences again (not too much work, is it ?).

V 2.1 : January 1999. The name statement problem has now been solved : you can set the 4 uppercase alphabetic name for your resource file in the options dialog. The generated constant file is now in OPL format, no more need to import it afterwards. The program can now generate files with bigger sizes (over 16-32kb).

How it works

This program takes a database with at least two fields as argument and returns two files : a standard rsc file that can be used in any OPL program with the standard functions (LOADRSC&, READRSC$, READRSCLONG&, UNLOADRSC), and a text file containing some constants to be imported to an opl file for calling the messages within your program.

The main advantages of this program is the possibility to compile the rsc files directly on the EPOC32 machine and to import the data you want to use as a resource from almost any kind of format (via the data program and PsiWin...).

When you run RSCcompiler for the first time in a directory, it will generate an ini file. Be careful to press the "FilePaths..." button to set the source and targets paths before running the compiler.

Usage

The best way to understand is to try the example database provided in this package and to run the program on it. The general instructions follow :

You need a database in the psion or opl format with at least two fields and a maximum of 10 fields (you could handle 9 different languages in the same database in this case !). The frist field will contain the constants description and the following ones the language dependant resources for up to 9 languages.

The constant definitions : it is a simple string such as menu_file_open_text,... Warning : it's up to your attention to check that you don't use twice the same definition. By the way, if you leave some spaces (forbidden for variables or constants names in OPL), they will automatically be replaced by underscores "_" for OPL syntax compatibility !

The resources definitions : they can be either a simple text or a long integer. The only way they differ is that the long integer resource string has to begin by the "&" character ; no space is needed after it but the specified integer must be in decimal. You can put the "&" anywhere in a string resource but not at the begining to avoid confusion.

Main screen : you get there a reminder of the current paths, a language choice and a check box to build or not the constant definitions. You also have 4 buttons to call the path preferences or program options dialogs, to run the program, or to quit.

Paths preferences : you have to choose there the path of your data file and the two paths of the output rsc and constant definitions files.

Program options : The first preference is a string that contains the languages definitions in the order they appear in your database ; they MUST have only two letters and be separated by a coma as the string is used for a dCHOICE dialog. The "add language name" checkbox allows you to automatically add the two letters of the selected language to the generayed resource file name thus preventing you to rename them and to compile several languages in one session. The next checkbox enables the special syntax feauture to be scanned (see below). The NAME statement is an input for your resource ID, see below.

Special syntax : you can use the "\$n\" string in a string field to insert the special character of ASCII code n. The value n must be decimal.

Resource ID : Several resource file can be used in a single program as far as they all have a different name statement. This name must be made of 4 uppercase alphabetic characters..

It is recommended that you run this program in the directory in which you have the initial data file because this programs automatically displays a file choice dialog starting at the folder in which it is located.

After writing your database, run RSCcompiler. Choose the right file, set the correct fileds references for the constant and the resource. Run it by pressing ENTER. All you have to do then is to rename the RSC file you get.

WARNING ! : there is no error handling so far but it can be added if necessary. I will appreciate any feedback to improve this utility.

Future plans

Other features will be added along with my needs or other users suggestions.

For any further information or suggestions, contact the author : "Guillaume Sabouraud ".

From the same author :